The Business Master (3rd Edition)

home *** CD-ROM | disk | FTP | other *** search

/ The Business Master (3rd Edition) / The Business Master (3rd Edition).iso / files / wordmisc / writstyl / wstyle.doc < prev next >

Wrap

Text File | 1992-02-20 | 82.1 KB | 2,179 lines

The Wintertree Writing Style Analyzer Wintertree Software Inc. Wintertree Software Inc. makes no warranty, expressed or implied, for the fitness of this product for any purpose. Wintertree Software Inc. will not be held responsible for any loss or damage, direct or indirect, caused by the use or misuse of this product. WStyle is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find WStyle useful and want to continue using it, you must make a registration payment of $25.00 to Wintertree Software Inc. The $25.00 registration fee will license one copy for use on any one computer at any one time. Commercial users of WStyle must register and pay for their copies within 30 days of first use or their license is withdrawn. Site-license arrangements may be made by contacting Wintertree Software Inc. You are encouraged to pass a copy of WStyle along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive a copy of the latest version of WStyle and a printed copy of the user's guide. Please see ORDER.TXT for ordering instructions. MS-DOS is a trademark of Microsoft Corporation. WordPerfect is a trademark of WordPerfect Corporation. The Wintertree Writing Style Analyzer and User's Guide are Copyright 1992 by Wintertree Software Inc. Wintertree Software Inc. 43 Rueter Street, Nepean, Ontario, Canada K2J 3Z9 (613) 825-6271 Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1 Installing WStyle . . . . . . . . . . . . . . . . . . . . 1 About Writing Style . . . . . . . . . . . . . . . . . . . . . 2 Using WStyle . . . . . . . . . . . . . . . . . . . . . . . . 3 Writing-Style Statistics . . . . . . . . . . . . . . . . . . 9 Writing-Style Problems . . . . . . . . . . . . . . . . . . 13 Customizing WStyle . . . . . . . . . . . . . . . . . . . . 17 Setting Options . . . . . . . . . . . . . . . . . . . . 17 Configuring WStyle . . . . . . . . . . . . . . . . . . . 19 Editing Problem Patterns . . . . . . . . . . . . . . . . 25 Limitations . . . . . . . . . . . . . . . . . . . . . . . . 29 References . . . . . . . . . . . . . . . . . . . . . . . . 31 Wintertree Software Inc. WStyle User's Guide Introduction The Wintertree Writing-Style Analyzer -- WStyle for short (pronounced "Double-you Style") -- helps improve your writing style in two ways. First, it examines your writing for common problems, such as redundant words, wordy phrases, and awkward sentence structure. Second, it analyzes your writing style and presents statistics that tell you where your writing is weak and where it is strong. Although WStyle is not a substitute for an independent review, it can help you to write more clearly and directly and avoid common writing- style errors. System WStyle runs on MS-DOS-compatible computers. You Requirements can install WStyle on a hard disk or a floppy diskette. WStyle can check files produced by most word-processing programs. README.TXT The WStyle distribution contains a file called README.TXT. This file describes any changes made to WStyle since this manual was printed. We suggest you read README.TXT before using WStyle. Installing WStyle To install WStyle, create a directory called WSTYLE. Next, copy the following files to the WSTYLE directory: WSTYLE.EXE WSTYLE.WSP WSTYLE.INF Finally, edit the PATH environment variable in your AUTOEXEC.BAT file to include the WSTYLE directory. Refer to your MS-DOS user's guide for instructions on how to do this. For example, if you created the WSTYLE directory under C:\, you might edit your PATH variable to look like this: PATH=C:\DOS;C:\123;C:\WP51;C:\WSTYLE 1 WStyle User's Guide Wintertree Software Inc. About Writing Style The term "writing style" may mean different things to different people. Certainly, not everyone agrees on what constitutes good style. By "writing style" we mean the characteristics of writing that refer to its quality. There is good and bad writing style and everything between. Writing style is a step beyond the competency of correct spelling, punctuation, and grammar. Writing style is a measure of the quality of a written work. We have taken the position that the goal of writing is to convey information to the reader. Good writing, then, conveys information effectively: it is clear and direct. In developing WStyle, we researched the factors that affect how well information is conveyed. Because WStyle is a computer program, we were forced to concentrate on those factors that we could feasibly program. We arrived at these four general factors: 1. Use of the active voice over the passive voice 2. Word economy 3. Readability 4. Word choice. Many other important factors, such as organization and elegance, were omitted because we could find no feasible way of incorporating them into a computer program. The "Limitations" section states what WStyle can and cannot do. One final note on writing style: We do not consider ourselves experts on this subject. WStyle is the product of many hours of research. Most of the ideas in WStyle are the brainchildren and learned observations of the people whose books are cited in the "References" section. 2 Wintertree Software Inc. WStyle User's Guide Using WStyle This section describes how to run and operate WStyle. WStyle analyzes the text in a document prepared using a word-processing program. It points out common writing-style problems as it goes. When it has completed its analysis, WStyle displays some statistics which profile your writing style. You can tell WStyle which document to check in two ways: 1. By entering the name of the document file on the command line when you start WStyle 2. By selecting the "Check doc" action from WStyle's main screen. Specifying the The easiest way to run WStyle is to enter the name document name on of the program, "WStyle," on the DOS command line the command line followed by the document file name. For example, if you want to analyze a document called MEMO.TXT, and MEMO.TXT is in the current directory, enter the following command when you see the DOS prompt: wstyle memo.txt If you prefer, you can omit the document file name from the command line. You then tell WStyle which document to check by invoking the "Check doc" action (F1) from WStyle's main screen (described below). Problem-reporting You can enter two options on WStyle's command level options line: the problem-reporting level and the target reader's level. The "Customizing WStyle" section defines the meanings of these options. You can enter the problem-reporting level option ("/r") on the command line like this: /r n "n" is the problem reporting level (0 - 9). 3 WStyle User's Guide Wintertree Software Inc. Target-reader's The "/t" option defines the target-reader's level: level option /t n "n" is the number of years of schooling you expect the target reader to have. For example, to analyze a document called MEMO.TXT, set the problem- reporting level to 6, and the target-reader's level to 11.5, enter the following command line: wstyle /r 6 /t 11.5 memo.txt Main screen If you run WStyle with a document file name on the actions command line, it analyzes your document immediately. If you omit the document file name from the command line, WStyle displays a series of actions on the bottom line of the screen: F1-Check Doc F2-Options F3-Patterns Esc-Exit Check Doc (F1) Tells WStyle to check a document. WStyle displays a list of files; see "Selecting a File," below. Options (F2) Lets you change some of WStyle's options. See the "Customizing WStyle" section for more details. Patterns (F3) Lets you view and edit WStyle's writing-style problem patterns. See the "Customizing WStyle" section for more details. Exit (Esc) Exits WStyle and returns to DOS. Selecting a file When you invoke the "Check Doc" action, WStyle presents a file-selection form. The file-selection form lists all the files in a directory which match a specified pattern. The top line of the form shows the directory and pattern. Both the directory and pattern are changeable. WStyle highlights one of the file names in the form. You can highlight a different file by using the arrow keys. If the directory contains more files than can fit on the display, the "Page Up" and "Page Down" keys display more names. Note: The file-selection form can keep track of up to 128 file names. If the pattern matches more than this number of files, WStyle replaces the last file name with "Too Many!" When this happens, edit the file-name pattern (see below) to make it 4 Wintertree Software Inc. WStyle User's Guide more specific. For example, change a file-name pattern like "*.*" to "*.DOC". File-selection At the bottom of the screen, WStyle displays some form actions actions: F1-Open F2-Edit Path Esc-Quit Open (F1) WStyle opens the highlighted file. If the file name is a regular file, WStyle checks its contents. If the file name is a directory, WStyle enters it and displays its contents. Edit Path (F2) WStyle lets you edit the current directory name and file pattern. Use the left- and right-arrow keys to position the cursor within the path. The "Delete" key and "Backspace" keys delete characters. Typed characters are inserted at the cursor position. Press the "Enter" key when you are done. Cancel (Esc) WStyle closes the file-selection form and returns to the main-screen actions. Writing-style Regardless of the method you choose to start it, problem report WStyle examines the text in your document, collecting information about your writing style and looking for common writing-style problems. WStyle display each word it reads from your document. It also displays a progress bar which shows you what portion of the document it has examined. When it encounters a writing-style problem, WStyle displays a problem report: The following problem was encountered in D:\DOC\MEMO.TXT: Problem: connected together Description: Redundant Suggestion: Use "connect" Note: The writing-style problems which WStyle reports are really warnings brought to your attention. The problems do not necessarily indicate errors in your writing. Unlike a spelling checker, which states conclusively which words are spelled incorrectly, WStyle simply points out places in your writing that match patterns associated with common writing-style problems. You must decide whether the problem is significant to you. 5 WStyle User's Guide Wintertree Software Inc. Furthermore, do not assume that WStyle detects and reports all the writing-style problems in your document. See the "Limitations" section for a more detailed description of what WStyle can and cannot do. Problem The problem report describes the writing-style problem. The "Problem" area shows the word or phrase containing the problem. The problem word or phrase is among the last highlighted words in the context area. Description The "Description" area contains a description of the problem. The "Writing Style Problems" section of this guide explains what the various descriptions mean. Suggestion WStyle offers in the "Suggestion" area of the problem report a suggestion for correcting or improving your text. Sometimes WStyle suggests a different wording of a phrase. Sometimes the problem is a symptom of poor or awkward sentence structure, so WStyle suggests that the entire sentence be rewritten. Sometimes the "problem" is really a warning -- WStyle may warn you that you have used a word which people often use incorrectly, even if you have used the word correctly. The "Suggestion" area contains the correct definition of the word you used, so you can verify you used it correctly. Note: The "Ignore" action (F4) prevents WStyle from reporting the displayed problem again for the remainder of the document. You can also permanently stop WStyle from reporting certain problems. See the "Customizing WStyle" section for instructions. Problem-report When WStyle displays a problem report, it also actions presents a series of actions at the bottom of the screen: F1-Continue F2-Save F3-Print F4-Ignore Esc-Quit You invoke an action by pressing the function key next to the name of the action. Continue (F1) WStyle continues analyzing your document. Use it after you have read the problem report. 6 Wintertree Software Inc. WStyle User's Guide Save (F2) WStyle saves the problem report in a disk file. The disk file is saved in the same directory as the document file, and has the same name as the document file with a "Wnn" extension ("nn" is a number ranging from 01 to 99; WStyle uses a new number for each document checked in the same directory). For example, if you invoke the "Save" action while checking a document called MEMO.NR, WStyle will save the problem report in a file called MEMO.W01. The disk file created by WStyle contains the same problem-report information presented on the screen. Print (F3) WStyle prints the problem report on a printer. The printout contains the same problem report information presented on the screen. Ignore (F4) WStyle ignores the displayed problem if it occurs again in the same document. WStyle will, however, report the problem if it appears the next time you check a document. To ignore a problem permanently, see the "Configuring WStyle" section. Quit (Esc) WStyle stops checking the document and returns to the main screen. Statistics report When WStyle has finished checking your document (either because it has reached the end or you selected the "Quit" action), it displays some writing-style statistics. See the "Writing-Style Statistics" section for more information. Correcting You cannot currently edit your document within problems WStyle to correct reported problems. We suggest the following procedure for fixing problems reported by WStyle. If your word-processing program lets you load more than one document at a time, save WStyle's problem reports to a disk file, then load the "Wnn" file created by WStyle into your word processor with your document. For example, suppose you have created a document in WordPerfect called CHAP1.DOC. Have WStyle check CHAP1.DOC and save any significant problem reports (use the F2 key). Exit WStyle, then start WordPerfect. Import CHAP1.DOC into WordPerfect. Now, enter 7 WStyle User's Guide Wintertree Software Inc. WordPerfect's "switch" command (Shift/F3) to switch to the alternate document. Load CHAP1.W01 (actually, the CHAP1.Wnn file with the highest number) into WordPerfect. Use WordPerfect's "switch" command to flip between CHAP1.DOC and the WStyle problem reports as you correct the document. If your word processor cannot load more than one document at a time, print significant problems displayed by WStyle (use the F3 key). Use the printout to locate and correct problems. If you do not have a printer, you must record significant problem reports by hand for later correction using your word processor. 8 Wintertree Software Inc. WStyle User's Guide Writing-Style Statistics When it has finished checking your document, WStyle displays some statistics: Finished checking D:\DOC\MEMO.TXT. * 605 problems were detected and 106 were reported. * The document contains 5824 words and 375 sentences. On average, each word contains 1.7 syllables and each sentence contains 15.5 words. * 68% of the sentences use the active voice. Use of the active voice in this document makes the writing clear and direct. * On average, the reader must have 12.8 years of schooling to understand the document. Suggestion: use smaller words and shorter sentences to lower the writing to the target reader's level (10.0 years). * The overall style score for this document is 84% (excellent). Problem counts The problem counts show the number of writing- style problems detected and reported by WStyle. These numbers will be different if your problem- reporting level setting prevented some problems from being reported. Word and sentence The word and sentence counts show the size of your counts document in words and sentences. These can be useful if your writing must meet size restrictions. Average word size The average word-size shows the average number of syllables per word. This statistic tells you whether you tend to use small words (about 1.0 syllables per word) or large words (more than about 2.0 syllables per word). Average sentence The average sentence-length shows the average length number of words per sentence. This statistic tells you whether you tend to use short sentences (about eight words per sentence or fewer) or long sentences (about 20 words per sentence or more). Active voice The active-voice percentage shows what portion of sentences use the active voice. The active voice 9 WStyle User's Guide Wintertree Software Inc. is associated with clear, direct writing. Sentences written in the active voice use action verbs (verbs that describe action), as opposed to passive verbs (verbs that describe conditions or states of being). Text written in the passive voice has a vague, detached quality when read. Passive verbs WStyle treats forms of the verb "to be" as passive verbs. WStyle considers the following as forms of the verb "to be": "be," "is," "was," "were," "been," "are," and "am." These words appearing in contractions (such as "isn't" and "weren't") are also considered passive. Rewriting passive To make your writing more direct, look for sentences sentences containing passive verbs and try to rewrite them. Often, the subject of passive sentences is implied, as in the following example. "The report will be prepared in the near future." Adding a subject makes the sentence clearer. "The report will be prepared by our staff in the near future." The sentence is still indirect and passive; it uses a passive verb ("be"). Moving the subject ("our staff") to the beginning eliminates the passive verb and makes the sentence active, direct, and clear. "Our staff will prepare the report soon." When the passive Mixing a few passive-voice sentences (perhaps voice is 25-30 percent) with active-voice sentences may appropriate improve the rhythm and break up the newspaper-style monotony of text written entirely in active-voice sentences. In technical writing especially, the passive voice is often appropriate since the subject may be less significant than the action or object. Readability WStyle displays a readability grade. The readability grade shows the approximate number of years of schooling on average needed to understand the document. The readability grade is based on the number of "big" words versus the number of 10 Wintertree Software Inc. WStyle User's Guide "small" words and the average sentence length. The statistic is taken from a readability formula called the "Fog Index." WStyle compares the readability grade for your document with the value you supplied for the target-reader's level (see the "Customizing WStyle" section). If they are significantly different, WStyle offers some advice on changing your writing to suit the target-reader's level. Overall-style The overall-style statistic is a general rating of score your writing style. The score is expressed as a percentage, with 100% being the best possible score. A word which qualifies the score follows the percentage. The overall-style score is based on the following factors: 1. Active voice: The portion of sentences that use only active verbs. 2. Word economy: The ratio of words that convey meaning (verbs, nouns, adjectives, and adverbs) to supporting words (prepositions, articles, etc.). 3. Readability: The difference between the document's readability grade and the target- reader's level. 4. Word choice: Ratio of direct, active verbs and concrete nouns to abstract nouns and verbs transformed to nouns (e.g., "construct" vs. "construction"; "establish" vs. "establishment"; "advocate" vs. "advocacy"). Improving the To improve the overall-style score, concentrate on overall-style the areas listed below. score Use the active voice. Consider rewriting sentences containing passive verbs. Rewrite wordy phrases containing several articles and prepositions: * "the findings of the committee" becomes "the committee's findings" 11 WStyle User's Guide Wintertree Software Inc. * "at the present time" becomes "now" * "on the advice of our attorney" becomes "our attorney advised us to" Follow WStyle's advice on adjusting word and sentence lengths to suit the target reader. Avoid abstract nouns and verbs transformed to nouns. Turn patterns like "the ...tion" of and "the ...ment of" back into verbs. Statistical At the bottom of the screen, WStyle displays some report actions actions: F2 Save F3 Print Esc Done Save (F2) WStyle saves the statistical report to a disk file. WStyle appends the report to the same disk file used to save problem reports (the "Wnn" file). See the "Using WStyle" section for more information. Print (F3) WStyle prints the statistical report. Done (Esc) WStyle returns to the main screen. 12 Wintertree Software Inc. WStyle User's Guide Writing-Style Problems WStyle checks documents for the common writing- style problems listed below. American spelling WStyle reports spelling that is inconsistent with the spelling preference you selected (see the "Customizing WStyle" section). If you selected a preference for British spelling, WStyle reports any words spelled in the American style (e.g., "defense", "color", and "traveling"). Archaic Words that are no longer in common usage. Awkward Words and phrases that are too informal or do not read well, although they may not be in error. British spelling WStyle reports spelling that is inconsistent with the spelling preference you selected (see the "Customizing WStyle" section). If you selected a preference for American spelling, WStyle reports any words spelled in the British style (e.g., "defence", "colour", and "travelling"). Can often be Some words can be omitted without altering the omitted meaning or impairing the readability of a sentence. For example, "that" can safely be omitted in the sentence, "He told me that he was coming." Some occurrences of "that" cannot be removed: "I want that one." Classifying a Phrases that turn a single object into a class, singular such as "this kind of a car" (should be "this kind of car"). Confusing word Words that may be misinterpreted, such as "biweekly". Some people interpret "biweekly" to mean "twice per week" while others interpret it as "once every two weeks." Contraction WStyle checks for common contractions (e.g., "can't" and "won't") which should be expanded in formal writing. Double comparison Comparison adjectives and adverbs such as "faster" and "fastest" which are themselves qualified with comparison adverbs, such as "less" or "most." For example, "most fastest," "more better," and "less smaller." 13 WStyle User's Guide Wintertree Software Inc. Double negative WStyle detects some cases of negative words which are qualified by negative adjectives, such as "not uncommon." These are unnecessarily confusing to the reader. Doubled word The same word appearing twice in a row, as in "Paris in the the spring." Incorrect form of This abbreviation occurs incorrectly so often that "e.g." WStyle checks for it specifically. The correct form is "e.g.," as in "e.g., the sun, the moon, and the stars." Incorrect form of This abbreviation occurs incorrectly so often that "i.e." WStyle checks for it specifically. The correct form is "i.e.," as in "i.e., the reset switch." Jargon Words with a technical meaning applied in non- technical writing ("parameter" and "interface") or words and phrases commonly associated with "managementspeak" ("time frame" and "prioritize"). Last word of Prepositions (such as "for," "with," or "to") sentence is a appearing as the last word of a sentence. While preposition this style is gaining acceptance, a sentence ending with a preposition may benefit from rewriting. Missing or Periods or commas not followed by a space ("Mix incorrect spacing butter, eggs,and sugar...") or incorrectly preceded by a space ("The old man tipped his hat ,then disappeared.") These problems are usually typographical errors. Often confused Words that people often confuse with other words. with... These words may be confused because they sound similar ("affect" and "effect"). They may also be confused because the difference in the meanings is subtle ("imply" and "infer"). Often misused Words that people often mistakenly use in place of for... correct words. "Feel," for example, is often misused for "think," "believe," or "estimate," as in "I feel the report will be ready by the end of the week." 14 Wintertree Software Inc. WStyle User's Guide Passive verb Verbs that describe conditions or states of being, rather than actions. Passive verbs are symptoms of the passive voice. See the "Writing-Style Statistics" section for more information. Period or comma Punctuation placed incorrectly inside or outside outside quotation quotation marks. Periods and commas should be placed inside quotation marks. Colons and semicolons should be placed outside. Qualifying an Absolute adjectives which are qualified with absolute comparison adjectives, as in "more complete," "most perfect," and "very unique." Redundant Phrases like "connect together," "final end," and "repeat again." It's amazing how easy it is to use phrases like this without being aware that they are redundant. Sentence starts WStyle warns you if the first word of a sentence with a small doesn't start with a capital letter. Sometimes letter WStyle reports this in error; see the "Limitations" section for more information. Spelled-out WStyle reports spelled-out numbers that should be numbers written in digit form. This includes any number greater than nine. Stilted "Fifty-cent" words that may make your document hard to read. Too few "(" or Parentheses that are closed but never opened. See too many ")" "Too many '(' or too few ')'." Too many "(" or Parentheses that are opened but never closed. too few ")" WStyle also reports unbalanced braces ("{", "}") and brackets ("[", "]"). WStyle reports these problems at the end of your document. Too many The sentence contains more prepositional phrases prepositions than are permitted. Sentences with strings of prepositional phrases are difficult to follow. Example: "The leader of the committee on the status of the study of incomplete projects could not attend." You can change the number of permitted prepositional phrases per sentence; see the "Customizing WStyle" section. 15 WStyle User's Guide Wintertree Software Inc. Unbalanced WStyle informs you if there is an odd number of quotation marks quotation marks in your document. WStyle reports this problem at the end of your document. Usage error Incorrect combinations of words. Many of these errors come from writing the way we hear; for example, writing "suppose to" instead of "supposed to," or "could of" instead of "could have." Vague Adjectives that convey little meaning to the reader, such as "nice" and "very." These should be replaced with specific adjectives. Wordy Phrases containing superfluous words. Eliminating unneeded words tightens the text. 16 Wintertree Software Inc. WStyle User's Guide Customizing WStyle You can change some aspects of WStyle to suit your preference: * The severity level at which writing-style problems are reported (see the "Setting Options" and "Configuring WStyle" topics in this section) * The colors displayed on the screen (see the "Configuring WStyle" topic) * The writing-style problem patterns (see the "Editing Problem Patterns" topic) * Whether American or British spelling rules are used (see the "Configuring WStyle" topic) * The relative importance of the factors that influence the overall-style statistic (see the "Configuring WStyle" topic) * The reading ability of your document's target readers (see the "Setting Options" topic). Setting Options The "Options" action (F3) in WStyle's main screen presents the options form: Reporting Level: [5] Target Reader Level: [10.0] You can use this form to temporarily change the way WStyle analyzes a document. Currently, you can change the problem-reporting level and the target- reader's level. Note: You can also set the problem-reporting level or the target-reader's level on WStyle's command line. See the "Using WStyle" section for more information. Problem-reporting The problems reported by WStyle range from minor level warnings and suggestions to serious errors. Each problem reported by WStyle has a severity associated with it. The reporting-level option 17 WStyle User's Guide Wintertree Software Inc. defines the severity threshold for problems which WStyle reports. If the problem-reporting level is "0," WStyle reports all problems it detects. If the level is "9," WStyle reports only the most serious problems. Generally, selecting a high reporting level decreases the number of problems which WStyle reports, and selecting a low level increases the number. For example, if you select "5" as your problem-reporting level, WStyle reports only problems with a severity of five and above, but does not report problems with a severity less than five. You can change the severity of each problem pattern; see the "Editing Problem Patterns" and "Configuring WStyle" topics in this section. Target-reader's The target-reader's level defines the average level number of years of schooling you expect your document's audience to have. The number of schooling years is an approximation of reading ability. WStyle uses this number in its writing- style analysis (see the "Writing-Style Statistics" section. What number should you use here? Try to think of the target-reader's schooling in terms of grades. If you are writing for professionals, use 12.0 or greater (college and beyond). If you are writing for school-aged children, use their grade number. For example, if you are writing a primary-school story aimed at children in grade 2, enter 2.5. If you are writing for a wide audience, use 10.0 (the default). Done (Esc) Once you have set the problem-reporting level or target-reader's level, press the "Esc" key to return to WStyle's main screen. WStyle uses the entered values until you return to DOS. Next time you run WStyle, it will revert to the default values. To change the defaults, see the "Configuring WStyle" topic. 18 Wintertree Software Inc. WStyle User's Guide Configuring WStyle You can configure some WStyle options by editing a file called WSTYLE.INF. This file is located in the WSTYLE directory you created when you installed WStyle (see "Installing WStyle"). You must change WSTYLE.INF from MS-DOS; you cannot edit it from within WStyle. Editing To change an option in WSTYLE.INF, you need a text WSTYLE.INF editor capable of loading and saving ASCII files. The "edlin" editor supplied with MS-DOS will do, but unless you have used "edlin" before, we don't recommend it. The "edit" editor supplied with MS- DOS 5.0 is much easier to use. You can use any text-editing program which can edit your AUTOEXEC.BAT or CONFIG.SYS files. Option entries The entries in WSTYLE.INF look like this: REPORTING_LEVEL=3 The option name (in this case, "REPORTING_LEVEL") appears to the left of the equal sign ("="). The option value (in this case, "3") appears to the right. This sample entry assigns the value "3" to the REPORTING_LEVEL option. Note that no spaces appear before or after the equal sign. Comment lines WStyle ignores blank lines and lines beginning with a "#" character in WSTYLE.INF. You can use the "#" character to mark comment lines. Error checking Edit the option values in WSTYLE.INF carefully: WStyle does little checking. The following paragraphs describe each configurable option. Problem-reporting The REPORTING_LEVEL option defines the default level problem-reporting threshold. WStyle reports only problems at this severity or greater. You can temporarily change the reporting level when WStyle runs with the "Options" action (see "Setting Options"). You can also set the level on the command line (see "Using WStyle"). The option value is a number ranging from 0 to 9. Example: REPORTING_LEVEL=5 19 WStyle User's Guide Wintertree Software Inc. Spelling-rules The SPELLING_PREFERENCE option defines your preference preference for American or British spelling rules. For example, if you specify a preference for American spelling rules, WStyle will report words spelled in the British style. The option value can be "American" or "British." Examples: SPELLING_PREFERENCE=American SPELLING_PREFERENCE=British Problem-pattern The PATTERN_FILE option defines the location and file name name of the file containing writing-style patterns. WStyle uses these patterns when analyzing a document. The file WSTYLE.WSP is provided with WStyle, but you can create custom pattern files (see "Editing Problem Patterns"). The option value is the path name of the problem- pattern file. If you don't specify a full path, WStyle looks for the file in the directory containing WSTYLE.EXE. Examples: PATTERN_FILE=D:\DOC\TOOLS\WSTYLE\FICTION.WSP PATTERN_FILE=MEDICAL.WSP Problem Most writing-style problem patterns are defined in severities the WSTYLE.WSP file provided with WStyle. But some patterns, because of their complexity, are built in to the WStyle program itself. The WORD_USAGE_SEVERITY, PUNCTUATION_SEVERITY, and SPELLING_SEVERITY options define the severities of the built-in problem patterns. The severity values indicate the importance of the problems. You can include the problems or exclude them by changing the problem-reporting level. Word-usage- The WORD_USAGE_SEVERITY option defines the problem severity severity of problems related to word usage. These problems include: * Prepositions at the ends of sentences * Too many prepositional phrases in a sentence * Doubled words. 20 Wintertree Software Inc. WStyle User's Guide Punctuation- The PUNCTUATION_SEVERITY option defines the problem severity severity of problems related to punctuation. These problems include: * Incorrect forms of "e.g." and "i.e." * Missing or incorrect spacing * Punctuation placed incorrectly inside or outside quotation marks * Sentences starting with lower-case letters * Unbalanced parentheses, brackets, and quotation marks. Spelling-problem The SPELLING_SEVERITY option defines the severity severity of problems caused by conflicts between the spelling rules you use and your stated spelling- rule preference (see the SPELLING_PREFERENCE option). Note: Some spelling problem patterns are defined in WSTYLE.WSP. The SPELLING_SEVERITY option does not affect these. Severity-option The option values for the severity options are values numbers ranging from 0 to 9. Examples: WORD_USAGE_SEVERITY=7 PUNCTUATION_SEVERITY=4 SPELLING_SEVERITY=4 Word The STRICT_WORDS option indicates whether WStyle acceptability should exclude character strings which do not appear to be valid English words. The option value is "True" or "False." If you use WStyle to analyze documents prepared by a word-processing program, set the STRICT_WORDS option to "True." WStyle will ignore most formatting information inserted by your word-processing program. If you use WStyle to analyze ASCII text files, set the STRICT_WORDS option to "False." WStyle will then treat all alphabetic strings in your document as words. See the "Limitations" section for more information. Examples: STRICT_WORDS=True STRICT_WORDS=False 21 WStyle User's Guide Wintertree Software Inc. Style-factor WStyle calculates the "Overall style score" weights statistic from several factors: * Use of the active voice over the passive voice * Word economy * Readability * Word choice. WStyle analyzes your documents against these factors. It bases the overall-style score statistic (see the "Writing-Style Statistics" section) on the weighted sum of the factors. The ACTIVE_VOICE_WEIGHT, WORD_ECONOMY_WEIGHT, READABILITY_WEIGHT, and DICTION_WEIGHT options define the relative values of each factor to the overall-style score. The option values are numbers ranging from 0 to 100. Each weight indicates the relative importance of its associated factor expressed as a percentage. The values assigned to all four weight options must total 100. Default weights The default weights included with WStyle were calibrated by examining a ranked collection of writing samples. The samples were ranked according to our definition of writing-style quality (see "Writing Style"). You may wish to change the weights because you don't agree with the importance we place on each factor. You may, for example, write for an organization that favors the use of the passive voice. Our bias in favor of the active voice will unfairly score your writing style. Changing the If you decide to define a new set of weights, you weights may want to use the method we used. Obtain a collection of writing samples with quality ranging from poor to excellent (judged by whatever standards you prefer). Sort the samples in order of quality. Have WStyle analyze each sample. Using trial-and-error, change the style weights until WStyle scores the samples in the same order in which you sorted them. You may need to adjust the target-reader's level to suit the samples. Your degree of success in this process may vary depending on how closely your notion of writing- style quality agrees with ours. 22 Wintertree Software Inc. WStyle User's Guide Some example weight options follow (note that the values total 100): ACTIVE_VOICE_WEIGHT=25 WORD_ECONOMY_WEIGHT=30 READABILITY_WEIGHT=20 WORD_CHOICE_WEIGHT=25 Target-reader's The TARGET_READER_LEVEL option defines the default level average years of schooling you expect the readers of your document to have. You can temporarily change the target-reader's level when WStyle runs with the "Options" action (see "Setting Options"). You can also set the level on the command line (see "Using WStyle"). The option value is a positive floating-point number. Example: TARGET_READER_LEVEL=9.8 Screen colors If you use WStyle with a color monitor, you can change the colors WStyle uses. You can independently set the foreground (text) and background colors of the following screen areas: * Context: Used to show which word is being checked. Also used to present the document statistics, problem pattern, and options. * Problem report: Used to present writing-style problems. * Progress bar: Used to draw a horizontal bar showing how much of the document has been checked. * Function keys: Used to present action names and their associated function keys. * Alert: Used to display errors and other important messages. Color values Each color option value is a number ranging from 0 to 15. Use the following table to determine the number for each color: 23 WStyle User's Guide Wintertree Software Inc. 0 Black 8 Dark gray 1 Blue 9 Light blue 2 Green 10 Light green 3 Cyan 11 Light cyan 4 Red 12 Light red 5 Magenta 13 Light magenta 6 Brown 14 Yellow 7 Light gray 15 White Here are some example color options: CONTEXT_FG_COLOR=7 CONTEXT_BG_COLOR=1 PROBLEM_FG_COLOR=1 PROBLEM_BG_COLOR=3 PROGRESS_FG_COLOR=4 PROGRESS_BG_COLOR=7 FKEY_FG_COLOR=1 FKEY_BG_COLOR=15 ALERT_FG_COLOR=14 ALERT_BG_COLOR=4 Prepositional- The PREPOSITION_LIMIT option defines the maximum phrase limit number of prepositional phrases considered acceptable in a sentence. WStyle reports sentences containing more prepositional phrases than the limit permits. Typical prepositional phrases include "the roof of the house" and "the man in the moon." While these are acceptable individually, they can make sentences hard to follow and awkward when they are repeated. The option value is a positive number. Example: PREPOSITION_LIMIT=4 Active-voice The ACTIVE_VOICE_LIMIT option defines the minimum percentage limit percentage of sentences which use the active voice. WStyle compares your document's active- voice statistics against this limit (see the "Writing-Style Statistics" section). The option value is a number ranging from 0 to 100. Example: ACTIVE_VOICE_LIMIT=60 24 Wintertree Software Inc. WStyle User's Guide Editing Problem Patterns You can add, change, or delete the problem patterns WStyle uses to check your documents. Edit WStyle's problem patterns by selecting the "Patterns" action (F3) from WStyle's main screen. WStyle comes with a large set of problem patterns. You don't need to edit the problem patterns to use WStyle. However, you may want to define your own problem patterns. You may also want to change the suggestion WStyle offers when it reports a problem, or change the severity of a problem. Custom pattern You can also define your own set of custom problem files patterns for different purposes. Possibilities include pattern sets for fiction, medical or legal terminology, children's books, advertising copy, and song lyrics. To create a custom problem-pattern file, copy WSTYLE.WSP to some appropriate name (e.g., FICTION.WSP). Change the PATTERN_FILE option in WSTYLE.INF to the name of the new file (see the "Configuring WStyle" topic). Run WStyle and edit the patterns as needed for your purpose. Removing problem You can delete WStyle's problem patterns, but we patterns do not recommended this. Instead, change the reporting level of the unwanted problem pattern to "0" and set your reporting level option (see "Set Options") to at least "1." Note: If you add many problem patterns, you may run out of memory. In this case, you must delete some of the existing patterns to make room for the new ones. WStyle shows one problem pattern at a time on the screen: Pattern: [a criteria ] Description: [Usage error ] Suggestion: [Criteria: plural ] Severity: [8] 25 WStyle User's Guide Wintertree Software Inc. Moving around The "Page Up" and "Page Down" keys display the previous and next patterns. WStyle presents the patterns in alphabetical order. A problem pattern consists of four fields: "Pattern," "Description," "Suggestion," and "Severity." Use the "Up Arrow" and "Down Arrow" keys to move the cursor between fields. Editing a problem You can change the contents of a field using pattern standard editing keys. Typed characters are placed in the field at the cursor position. Note that each field has a maximum size; WStyle beeps if you try to type past the end of a field. The "Left Arrow" and "Right Arrow" keys move the cursor back and forth in the current field. The "Delete" key deletes the character under the cursor. The "Backspace" key deletes the character to the right of the cursor. The "Clear" action (F6) clears the current field. Problem pattern The "Pattern" area contains a single writing-style pattern. The words that form a pattern may contain the wildcard characters "*" and "?". These are the same wildcard characters used on the DOS command line. In case you are not familiar with them, "*" matches any group of zero or more characters. "?" matches any single character. WStyle limits the wildcard characters to words. WStyle considers a word to be any collection of alphabetic characters. A word may contain embedded apostrophes. WStyle ignores other punctuation appearing in patterns. "Walk*" matches the words "walk", "Walks", "walking", and "Walkley's". WStyle is not case-sensitive. "*ing" matches any word ending in "ing". "A?*" matches any word that is at least two letters long and starts with "A" or "a". "*" matches any word. You can use wildcards in any word within a pattern. The first word in a pattern must start with a letter, not a wildcard. A pattern may contain up to eight words. Description Use the "Description" field to define a brief message that explains the problem. For cons- istency, try to use one of the descriptions WStyle uses (see the "Writing-Style Problems" section). Suggestion Use the "Suggestion" field to recommend a way of fixing the problem. 26 Wintertree Software Inc. WStyle User's Guide Severity Enter a number between 0 and 9 in the "Severity" field to define the severity of the writing-style problem. Problem-pattern The actions at the bottom of the screen tell editor actions WStyle what to do with the displayed pattern. F1-Change F2-Add F3-Delete F4-Search F5-Save F6-Clear Esc-Done Change (F1) To change the displayed problem pattern, edit the pattern, description, suggestion, or severity. Next, invoke the "Change" action (F1). Add (F2) To add a new writing-style problem pattern, edit the displayed pattern, description, suggestion, and severity to form a new pattern. Next, invoke the "Add" action (F2). Delete (F3) The "Delete" action removes the displayed problem pattern. As noted above, deleting the problem patterns provided with WStyle is not recommended. Search (F4) Use the "Search" action to locate a problem pattern containing a search key. WStyle prompts you for the key to locate: Enter search key: Enter or edit the key text, then press "Enter." WStyle searches for the key text in the "Pattern," "Description," and "Suggestion" fields. The "Search" action always searches from the first problem pattern. Use the "Search next" action to search for the next occurrence of the search key. Search next Use the "Search next" action to locate the next (Shift/F4) occurrence of the last search key entered using the "Search" action. The "Search next" action looks for the key starting with the problem pattern following the displayed one. Save (F5) The "Save" action saves the updated problem patterns to disk. WStyle will use the updated patterns each time you run it. Clear (F6) The "Clear" action deletes all the characters from the field on which the cursor is located. Use the "Clear" action to quickly empty a field. 27 WStyle User's Guide Wintertree Software Inc. Done (Esc) The "Done" action returns you to WStyle's main screen. When you invoke the "Done" action, the changes you have made take effect, but are not saved permanently. When you exit WStyle, the changes you made to the problem patterns will be lost. To save your changes permanently, use the "Save" action. Note: If you change many problem patterns, you may run out of string space. When this happens, save your changes (F5), then exit WStyle. Rerun WStyle and return to the problem-pattern editor. If WStyle still reports "Out of string space," you will have to delete some of the existing problem patterns before you can add new ones. 28 Wintertree Software Inc. WStyle User's Guide Limitations WStyle works mechanically. It matches a set of patterns against the words and phrases in a document. When it finds a match, it responds by displaying a problem report or recording a statistic. Like grammar checkers and other similar programs, WStyle has no idea of the meaning behind the words in a document. Sometimes it makes mistakes. For example, it warns that the phrase "number of" is often mistakenly used in place of "amount of," even in a sentence like "Always keep the telephone number of your fire department handy." You must consider each problem reported by WStyle to decide whether it is valid and significant. WStyle is not a substitute for an independent review. WStyle does not detect every writing-style problem. WStyle's assessment of writing style does not imply the writing is fit for any purpose. Tense Although it can recognize verbs in any tense, WStyle always makes its suggestions in the present tense. WStyle suggests you use "connect" instead of "connected together" or "connecting together." You may have to mentally translate WStyle's suggestions to the correct tense. Hyphenation codes Some word processors insert control codes within words to separate syllables for hyphenation. These control codes may confuse WStyle, causing it to miscount words or miss a problem it would otherwise catch. Disable your word processor's hyphenation feature if this is the case (see your word processor's user guide). Embedded Some word processors embed strings of characters character strings (for example, font names) within document files for control purposes. These strings are not normally visible. To WStyle, however, they are indistinguishable from words. You may see them in the context area, and they may make the word count and other statistics inaccurate. The easiest way 29 WStyle User's Guide Wintertree Software Inc. to avoid this problem is to use WStyle to check your document before adding special effects such as font changes and figures. If you can't do this, save your document in ASCII format before checking it with WStyle. Setting the STRICT_WORDS option to "True" may also help (see the "Customizing WStyle" section). Non-alphabetic WStyle normally ignores collections of characters strings that do not appear to be valid words. This includes numbers, times, and special characters. If you would like to disable this feature, set the STRICT_WORDS option to "False" (see the "Customizing WStyle" section). Sentences WStyle recognizes sentence endings by terminating punctuation: periods, question marks, and exclamation marks. WStyle may incorrectly believe a sentence has ended when this punctuation appears within a sentence. WStyle does, however, recognize common abbreviations terminated with periods within sentences. 30 Wintertree Software Inc. WStyle User's Guide References The following books were consulted during the preparation of WStyle. Baugh, L. Sue, Essentials of English Grammar, Passport Books, Lincolnwood, Ill. Lewis, Norman, Better English, Dell, NY. Montgomery, Michael and Stratton, John, The Writer's Hotline Handbook, New American Library, NY. Northey, Margaret, Making Sense: A Student's Guide to Writing and Style, Oxford University Press, Toronto. Opdycke, John B., Harper's English Grammar, Harper and Row, NY. Rosen, Leonard, The Everyday English Handbook, Dell, NY. Strunk, William and White, E.B., The Elements of Style, Macmillan Publishing, NY. Waldhorn, Arthur, and Zeiger, Arthur, English Made Simple, Doubleday, NY. Webster's Dictionary of the English Language, Lexicon Publications, NY. 31